home *** CD-ROM | disk | FTP | other *** search
/ Mac Easy 2010 May / Mac Life Ubuntu.iso / casper / filesystem.squashfs / usr / share / python-support / gnome-orca / orca / debug.py < prev    next >
Encoding:
Python Source  |  2009-04-13  |  8.9 KB  |  281 lines
  1. # Orca
  2. #
  3. # Copyright 2005-2008 Sun Microsystems Inc.
  4. #
  5. # This library is free software; you can redistribute it and/or
  6. # modify it under the terms of the GNU Library General Public
  7. # License as published by the Free Software Foundation; either
  8. # version 2 of the License, or (at your option) any later version.
  9. #
  10. # This library is distributed in the hope that it will be useful,
  11. # but WITHOUT ANY WARRANTY; without even the implied warranty of
  12. # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13. # Library General Public License for more details.
  14. #
  15. # You should have received a copy of the GNU Library General Public
  16. # License along with this library; if not, write to the
  17. # Free Software Foundation, Inc., Franklin Street, Fifth Floor,
  18. # Boston MA  02110-1301 USA.
  19.  
  20. """Provides debug utilities for Orca.  Debugging is managed by a debug
  21. level, which is held in the debugLevel field.  All other methods take
  22. a debug level, which is compared to the current debug level to
  23. determine if the content should be output."""
  24.  
  25. __id__        = "$Id: debug.py 3882 2008-05-07 18:22:10Z richb $"
  26. __version__   = "$Revision: 3882 $"
  27. __date__      = "$Date: 2008-05-07 14:22:10 -0400 (Wed, 07 May 2008) $"
  28. __copyright__ = "Copyright (c) 2005-2008 Sun Microsystems Inc."
  29. __license__   = "LGPL"
  30.  
  31. import traceback
  32. import pyatspi
  33.  
  34. # Used to turn off all debugging.
  35. #
  36. LEVEL_OFF = 10000
  37.  
  38. # Used to describe events of considerable importance and which will prevent
  39. # normal program execution.
  40. #
  41. LEVEL_SEVERE = 1000
  42.  
  43. # Used to decribe events of interest to end users or system managers or which
  44. # indicate potential problems, but which Orca can deal with without crashing.
  45. #
  46. LEVEL_WARNING = 900
  47.  
  48. # Used to indicate reasonably significant messages that make sense to end users
  49. # and system managers.
  50. #
  51. # For the purposes of Orca, LEVEL_INFO means display the text being sent to
  52. # speech and braille.
  53. #
  54. LEVEL_INFO = 800
  55.  
  56. # Used to indicate static configuration information to assist in debugging
  57. # problems that may be associated with a particular configuration.
  58. #
  59. # For the purposes of Orca, LEVEL_CONFIGURATION means display the various
  60. # apsects of whether a particular feature (e.g., speech, braille, etc.)
  61. # is enabled or not as well as details about that feature.
  62. #
  63. LEVEL_CONFIGURATION = 700
  64.  
  65. # Used for lowest volume of detailed tracing information.
  66. #
  67. # For the purposes of Orca, this is braille and keyboard input, script
  68. # activation and deletion, locus of focus changes, and visual changes
  69. # to the locus of focus.
  70. #
  71. LEVEL_FINE = 600
  72.  
  73. # Used for medium volume of detailed tracing information.
  74. #
  75. # For the purposes of Orca, this is for debugging speech and braille
  76. # generators and tracking the synthesis of device events.
  77. #
  78. LEVEL_FINER = 500
  79.  
  80. # Used for maximum volume of detailed tracing information.
  81. #
  82. # For the purposes of Orca, this is for tracking all AT-SPI object
  83. # events.  NOTE that one can up the debug level of AT-SPI object
  84. # events by setting the eventDebugLevel.  In addition, one can filter
  85. # events by setting eventDebugFilter to a regular expression that
  86. # matches event type names.
  87. #
  88. LEVEL_FINEST = 400
  89.  
  90. # Used for all detailed tracing information, even finer than LEVEL_FINEST
  91. #
  92. LEVEL_ALL = 0
  93.  
  94. debugLevel = LEVEL_SEVERE
  95.  
  96. # The debug file.  If this is not set, then all debug output is done
  97. # via stdout.  If this is set, then all debug output is sent to the
  98. # file.  This can be useful for debugging because one can pass in a
  99. # non-buffered file to better track down hangs.
  100. #
  101. debugFile = None
  102.  
  103. # The debug filter should be either None (which means to match all
  104. # events) or a compiled regular expression from the 're' module (see
  105. # http://www.amk.ca/python/howto/regex/).  The regular expression will
  106. # be used as a matching function - if the event type creates a match
  107. # in the regular expression, then it will be considered for output.  A
  108. # typical call to this method might look like:
  109. #
  110. # debug.eventDebugFilter = rc.compile('focus:|window:activate')
  111. #
  112. eventDebugLevel  = LEVEL_FINEST
  113. eventDebugFilter = None
  114.  
  115. def printException(level):
  116.     """Prints out information regarding the current exception.
  117.  
  118.     Arguments:
  119.     - level: the accepted debug level
  120.     """
  121.  
  122.     if level >= debugLevel:
  123.         println(level)
  124.         traceback.print_exc(100, debugFile)
  125.         println(level)
  126.  
  127. def printStack(level):
  128.     """Prints out the current stack.
  129.  
  130.     Arguments:
  131.     - level: the accepted debug level
  132.     """
  133.  
  134.     if level >= debugLevel:
  135.         println(level)
  136.         traceback.print_stack(None, 100, debugFile)
  137.         println(level)
  138.  
  139. def println(level, text = ""):
  140.     """Prints the text to stdout if debug is enabled.
  141.  
  142.     Arguments:
  143.     - level: the accepted debug level
  144.     - text: the text to print (default is a blank line)
  145.     """
  146.  
  147.     if level >= debugLevel:
  148.         if debugFile:
  149.             debugFile.writelines([text, "\n"])
  150.         else:
  151.             print text
  152.  
  153. def printObjectEvent(level, event, sourceInfo=None):
  154.     """Prints out an Python Event object.  The given level may be
  155.     overridden if the eventDebugLevel is greater.  Furthermore, only
  156.     events with event types matching the eventDebugFilter regular
  157.     expression will be printed.
  158.  
  159.     Arguments:
  160.     - level: the accepted debug level
  161.     - event: the Python Event to print
  162.     - sourceInfo: additional string to print out
  163.     """
  164.  
  165.     if eventDebugFilter and not eventDebugFilter.match(event.type):
  166.         return
  167.  
  168.     level = max(level, eventDebugLevel)
  169.  
  170.     text = "OBJECT EVENT: %-40s detail=(%d,%d)" \
  171.            % (event.type, event.detail1, event.detail2)
  172.     println(level, text)
  173.  
  174.     if sourceInfo:
  175.         println(level, "             %s" % sourceInfo)
  176.  
  177. def printInputEvent(level, string):
  178.     """Prints out an input event.  The given level may be overridden
  179.     if the eventDebugLevel (see setEventDebugLevel) is greater.
  180.  
  181.     Arguments:
  182.     - level: the accepted debug level
  183.     - string: the string representing the input event
  184.     """
  185.  
  186.     println(max(level, eventDebugLevel), string)
  187.  
  188. def printDetails(level, indent, accessible, includeApp=True):
  189.     """Lists the details of the given accessible with the given
  190.     indentation.
  191.  
  192.     Arguments:
  193.     - level: the accepted debug level
  194.     - indent: a string containing spaces for indentation
  195.     - accessible: the accessible whose details are to be listed
  196.     - includeApp: if True, include information about the app
  197.     """
  198.  
  199.     if level >= debugLevel and accessible:
  200.         println(level, getAccessibleDetails(accessible, indent, includeApp))
  201.  
  202. def getAccessibleDetails(acc, indent="", includeApp=True):
  203.     """Returns a string, suitable for printing, that describes the
  204.     given accessible.
  205.  
  206.     Arguments:
  207.     - indent: A string to prefix the output with
  208.     - includeApp: If True, include information about the app
  209.                   for this accessible.
  210.     """
  211.  
  212.     if includeApp:
  213.         app = acc.getApplication()
  214.         if app:
  215.             string = indent + "app.name='%s' " % app.name
  216.         else:
  217.             string = indent + "app=None "
  218.     else:
  219.         string = indent
  220.  
  221.     # create the States string
  222.     stateSet = acc.getState()
  223.     states = stateSet.getStates()
  224.     state_strings = []
  225.     for state in states:
  226.         state_strings.append(pyatspi.stateToString(state))
  227.     state_string = ' '.join(state_strings)
  228.  
  229.     # create the relations string
  230.     relations = acc.getRelationSet()
  231.     if relations:
  232.         relation_strings = []
  233.         for relation in relations:
  234.             relation_strings.append( \
  235.                           pyatspi.relationToString(relation.getRelationType()))
  236.         rel_string = ' '.join(relation_strings)
  237.     else:
  238.         rel_string = ''
  239.  
  240.     string += "name='%s' role='%s' state='%s' relations='%s'" \
  241.               % (acc.name or 'None', acc.getRoleName(),
  242.                  state_string, rel_string)
  243.  
  244.     return string
  245.  
  246.  
  247. # The following code has been borrowed from the following URL:
  248. # 
  249. # http://www.dalkescientific.com/writings/diary/archive/ \
  250. #                                     2005/04/20/tracing_python_code.html
  251. #
  252. import linecache
  253.  
  254. def traceit(frame, event, arg):
  255.     """Line tracing utility to output all lines as they are executed by
  256.     the interpreter.  This is to be used by sys.settrace and is for 
  257.     debugging purposes.
  258.    
  259.     Arguments:
  260.     - frame: is the current stack frame
  261.     - event: 'call', 'line', 'return', 'exception', 'c_call', 'c_return',
  262.              or 'c_exception'
  263.     - arg:   depends on the event type (see docs for sys.settrace)
  264.     """ 
  265.  
  266.     if event == "line":
  267.         lineno = frame.f_lineno
  268.         filename = frame.f_globals["__file__"]
  269.         if (filename.endswith(".pyc") or
  270.             filename.endswith(".pyo")):
  271.             filename = filename[:-1]
  272.         name = frame.f_globals["__name__"]
  273.         if name == "gettext" \
  274.            or name == "locale" \
  275.            or name == "posixpath" \
  276.            or name == "UserDict":
  277.             return traceit
  278.         line = linecache.getline(filename, lineno)
  279.         println(LEVEL_ALL, "TRACE %s:%s: %s" % (name, lineno, line.rstrip()))
  280.     return traceit
  281.